<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Custom predicate support</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Boost.Test">
<link rel="up" href="../testing_tools.html" title="Writing unit tests">
<link rel="prev" href="expected_failures.html" title="Expected failures specification">
<link rel="next" href="output_stream_testing.html" title="Output streams testing tool">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="expected_failures.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../testing_tools.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="output_stream_testing.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_test.testing_tools.custom_predicates"></a><a class="link" href="custom_predicates.html" title="Custom predicate support">Custom predicate
      support</a>
</h3></div></div></div>
<p>
        Even though supplied testing tools cover wide range of possible checks and
        provide detailed report on cause of error in some cases you may want to implement
        and use custom predicate that perform complex check and produce intelligent
        report on failure. To satisfy this need testing tools implement custom predicate
        support. There two layers of custom predicate support implemented by testing
        tools toolbox: with and without custom error message generation.
      </p>
<p>
        The first layer is supported by <a class="link" href="../utf_reference/testing_tool_ref/assertion_boost_level_predicate.html" title="BOOST_&lt;level&gt;_PREDICATE"><code class="computeroutput"><span class="identifier">BOOST_</span><span class="special">&lt;</span><span class="identifier">level</span><span class="special">&gt;</span><span class="identifier">_PREDICATE</span></code></a> family of testing tools.
        You can use it to check any custom predicate that reports the result as boolean
        value. The values of the predicate arguments are reported by the tool automatically
        in case of failure.
      </p>
<h6>
<a name="boost_test.testing_tools.custom_predicates.h0"></a>
        <span class="phrase"><a name="boost_test.testing_tools.custom_predicates.example_descr"></a></span><a class="link" href="custom_predicates.html#boost_test.testing_tools.custom_predicates.example_descr">Example:
        Custom predicate support using <code class="computeroutput"><span class="identifier">BOOST_</span><span class="special">&lt;</span><span class="identifier">level</span><span class="special">&gt;</span><span class="identifier">_PREDICATE</span></code></a>
      </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Code
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">example</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">bool</span> <span class="identifier">is_even</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="keyword">return</span> <span class="identifier">i</span><span class="special">%</span><span class="number">2</span> <span class="special">==</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_is_even</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_CHECK_PREDICATE</span><span class="special">(</span> <span class="identifier">is_even</span><span class="special">,</span> <span class="special">(</span><span class="number">14</span><span class="special">)</span> <span class="special">);</span>

  <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">17</span><span class="special">;</span>
  <span class="identifier">BOOST_CHECK_PREDICATE</span><span class="special">(</span> <span class="identifier">is_even</span><span class="special">,</span> <span class="special">(</span><span class="identifier">i</span><span class="special">)</span> <span class="special">);</span>
<span class="special">}</span>
</pre>
              </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Output
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_is_even"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">is_even</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">)</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="keyword">for</span> <span class="special">(</span> <span class="number">17</span> <span class="special">)</span>

<span class="special">***</span> <span class="number">1</span> <span class="identifier">failures</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"example"</span>
</pre>
              </td></tr></tbody>
</table></div>
<p>
        To use second layer your predicate has to return <code class="computeroutput"><a class="link" href="../../header/boost/test/tools/assertion_result_hpp.html#boost.test_tools.predicate_result">boost::test_tools::predicate_result</a></code>.
      </p>
<p>
        This class encapsulates boolean result value along with any error or information
        message you opt to report.
      </p>
<p>
        Usually you construct the instance of class <code class="computeroutput"><a class="link" href="../../header/boost/test/tools/assertion_result_hpp.html#boost.test_tools.predicate_result">boost::test_tools::predicate_result</a></code>
        inside your predicate function and return it by value. The constructor expects
        one argument - the boolean result value. The constructor is implicit, so
        you can simply return boolean value from your predicate and <code class="computeroutput"><a class="link" href="../../header/boost/test/tools/assertion_result_hpp.html#boost.test_tools.predicate_result">boost::test_tools::predicate_result</a></code>
        is constructed automatically to hold your value and empty message. You can
        also assign boolean value to the constructed instance. You can check the
        current predicate value by using <code class="computeroutput"><span class="keyword">operator</span><span class="special">!</span></code> or directly accessing public read-only property
        <code class="computeroutput"><span class="identifier">p_predicate_value</span></code>. The error
        message is stored in public read-write property <code class="computeroutput"><span class="identifier">p_message</span></code>.
      </p>
<h6>
<a name="boost_test.testing_tools.custom_predicates.h1"></a>
        <span class="phrase"><a name="boost_test.testing_tools.custom_predicates.example_descr0"></a></span><a class="link" href="custom_predicates.html#boost_test.testing_tools.custom_predicates.example_descr0">Example:
        Custom predicate support using class boost::test_tools::predicate_result</a>
      </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Code
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">example</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">predicate_result</span>
  <span class="identifier">compare_lists</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">l2</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="keyword">if</span><span class="special">(</span> <span class="identifier">l1</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">!=</span> <span class="identifier">l2</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">)</span>
  <span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">predicate_result</span> <span class="identifier">res</span><span class="special">(</span> <span class="keyword">false</span> <span class="special">);</span>

    <span class="identifier">res</span><span class="special">.</span><span class="identifier">message</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"Different sizes ["</span> <span class="special">&lt;&lt;</span> <span class="identifier">l1</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"!="</span> <span class="special">&lt;&lt;</span> <span class="identifier">l2</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"]"</span><span class="special">;</span>

    <span class="keyword">return</span> <span class="identifier">res</span><span class="special">;</span>
  <span class="special">}</span>
  <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_list_comparison</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">l2</span><span class="special">;</span>
  <span class="identifier">l1</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="number">1</span> <span class="special">);</span>
  <span class="identifier">l1</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="number">2</span> <span class="special">);</span>

  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">compare_lists</span><span class="special">(</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">l2</span> <span class="special">)</span> <span class="special">);</span>
<span class="special">}</span>
</pre>
              </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Output
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">28</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_list_comparizon"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">compare_lists</span><span class="special">(</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">l2</span> <span class="special">)</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span> <span class="identifier">Different</span> <span class="identifier">sizes</span> <span class="special">[</span><span class="number">2</span><span class="special">!=</span><span class="number">0</span><span class="special">]</span>

<span class="special">***</span> <span class="number">1</span> <span class="identifier">failures</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"example"</span>
</pre>
              </td></tr></tbody>
</table></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2022 Boost.Test contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="expected_failures.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../testing_tools.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="output_stream_testing.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
